Skip to content

add sdpi p history service option#452

Open
d-gregorczyk wants to merge 86 commits into
masterfrom
360-add-sdpi-p-history-service-option
Open

add sdpi p history service option#452
d-gregorczyk wants to merge 86 commits into
masterfrom
360-add-sdpi-p-history-service-option

Conversation

@d-gregorczyk

@d-gregorczyk d-gregorczyk commented Jun 19, 2025

Copy link
Copy Markdown
Contributor

☑ Mandatory Tasks

The following aspects have been respected by the pull request assignee and at least one reviewer:

  • Changelog update (necessity checked and entry added or not added respectively)
    • Pull Request Assignee
    • Reviewer

@d-gregorczyk d-gregorczyk linked an issue Jun 19, 2025 that may be closed by this pull request
@JavierEspina JavierEspina added this to the SDPi 2.2 Review milestone Jun 20, 2025
@PaulMartinsen

PaulMartinsen commented Jun 27, 2025

Copy link
Copy Markdown
Collaborator

Suggest changing R0512 to something like:

The provider shall transmit hm:HistoricMdib before transmitting each contiguous MDIB Sequence of Changes in the range requested by a consumer.
Note: this allows a provider to skip over gaps in its historical record while providing a MDIB Configuration for the consumer to apply changes to.

Possible need to tweak R0514 to something like:

For an MDIB Sequence of Changes that is requested from a SOMDS Provider, the SOMDS Provider shall provide exactly one MDIB Configuration in hm:ChangeSequence/hm:HistoricMdib for each contiguous MDIB sequence of changes.

Reasoning:

I was thinking more about the case where a provider starts providing history information but some of the history becomes unavailable before it is delivered. This could occur when:

  1. the consumer requests all (or most) of the history available, and
  2. the provider has limited memory and must discard old history records to make room for new changes to the mdib.

Some available options :

  1. End subscription:
  • The provider ends the history subscription, possibly with a (new) fault message.
  • The consumer starts a new history subscription and gets the next lot of data.
  • Repeat above steps each time items are lost from this history.
  1. Send with gaps:
  • The provider skips over the missing data and continues with what it has.
  • This is (probably?) useless to the consumer who doesn't have a mdib starting point to apply changes to.
  1. Send with gaps and starting mdib
  • The provider sends a full mdib snapshot (if this was requested by the original subscription)
  • Provider continues with change reports.

I quite like option 3 because:

  • it avoids multiple subscriptions (with potential race conditions) and doesn't require any special handling of fault messages on the consumer end.
  • the provider does its best to provide the information requested and while still letting the consumer create coherent mdib state.
  • its more likely to avoid lost history than if the consumer has to re-subscribe. The consumer can unsubscribe if it doesn't want any more data following a gap.

If the consumer didn't request a baseline mdib, we could sensibly fallback to option 1: end the subscription.

Note

Added to review.

@PaulMartinsen

PaulMartinsen commented Jun 27, 2025

Copy link
Copy Markdown
Collaborator

I would quite like to be able to omit waveform streams from the history because:

  1. they use up a lot of memory,
  2. an hour old waveform stream may often not be relevant anymore, and
  3. a deeper history of states other than waveform streams may be more relevant than a shallow history with waveform streams.

But the general case, where providers may omit any information, seems quite complicated and could be problematic. That is, important context may be lost.

Could the provider be allowed to omit waveform streams either:

  1. without disclosing this to the consumer (except perhaps in the documentation), or
  2. by sending RealTimeSamleArrayMetricState with @Off.

Or maybe there is no value in waveform streams in the historic record and they could just be omitted completely? That is, remove msg:WaveformStream from the HistoricReportType in HistoryModel.xsd

The main problem seems to be missing state versions (R1005), although I think we need to get rid of that one anyway.

Note

This is addressed in R0516 now

Comment thread asciidoc/listings/vol2-clause-appendix-a-mdpws-dev-32-subscribe.xml
Comment thread asciidoc/listings/vol2-clause-appendix-a-mdpws-dev-32-subscribe.xml Outdated
Comment thread asciidoc/volume2/dev-32/tf2-ch-a-mdpws-dev-32.adoc
Comment thread sources/history-service/HistoryModel.xsd
@PaulMartinsen

PaulMartinsen commented Jul 5, 2025

Copy link
Copy Markdown
Collaborator

The sequence diagrams weren't showing up for me. It looks like the action isn't copying them into the supplement from .ci\asciidoc-converter\images when it makes the zip file I downloaded from https://github.com/IHE/DEV.SDPi/actions/runs/15761385158

Note

Works now.

Comment thread asciidoc/plantuml/vol2-figure-dev-32-usecase-one-sequence-id.puml
Comment thread asciidoc/listings/vol2-clause-appendix-a-mdpws-dev-32-subscribe.xml Outdated
Comment thread asciidoc/volume2/history-service/tf2-ch-a-mdpws-history-service.adoc Outdated

Once the final report has been sent, the <<vol1_spec_sdpi_p_actor_somds_provider>> sends an empty report and ends the subscription to signify the end of the <<term_history_service>> request.

The <<term_history_service>> allows for limited filtering:

@PaulMartinsen PaulMartinsen Jul 5, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest that (for consistency with other profiles/standards) providers must support action based filtering and should support handle based filtering for the history service. So the protocol should support this somehow (see suggestion for one approach in another comment).

Because the history service is a foundational feature that may be used by large and small participants in the future, a little flexibility seems worthwhile even if the business cases aren't 100% clear at the beginning. I know low-resource providers would prefer that consumers only request what they need but providers have no control over that and best they can do is support the mechanisms.

Implementation doesn't seem hard to me if there is a mechanism in the protocol but I don't feel very strongly about this. Mostly because it requires consumers to use it for providers to benefit, which may not happen in practice.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest that (for consistency with other profiles/standards) providers must support action based filtering and should support handle based filtering for the history service.

Action based filtering does not have any meaningful effect on this port type as there is only one notification in there: To enable subscribing to one or more Notifications exposed by a HOSTED SERVICE, this profile defines a Filter Dialect designated "http://docs.oasis-open.org/ws-dd/ns/dpws/2009/01/Action". You would either be able to select everything or nothing - to select nothing, just do not send s subscribe :-)

Handle based filtering may be applicable to the history service, however, it is an optional feature in SDC Glue. I do not see embedded devices performing handle-based filtering on huge amounts of historic data. The limited filtering comes at a cost: less flexibility. But it provides embedded devices with the ability to efficiently store their historic data without performing expensive filtering operations when requested. If we receive proof that such an operation is efficiently processable and needed by the market today, I am totally happy to add it as a mandatory feature to the history service. The things for which there is no demand by the market, I would like to keep it out the spec for as long as possible. It's all big enough already...

a little flexibility seems worthwhile even if the business cases aren't 100% clear at the beginning.

Flexibility is always given - the current filter can be replaced by another one that supports nifty filtering options if we realize, the limited filtering does not suffice. Let's be evolutionary over revolutionary. ;-)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For action based filtering, I'm thinking of the StateEventService/EpisoidicMetricReport, StateEventService/EpisoidicAlertReport, ContextService/EpisoidicContextReport, etc. That is a consumer might decide they only want alert history from the day, then retrieve metric history for particular epochs around an alert.

We currently do handle based filtering on embedded devices. Mostly because 20701:R0039 said we should. Its only useful if consumers follow 20701:R0037 though and so far I haven't found any to validate interoperability of our prototype implementation unfortunately.

We don't have additional overhead to apply the filter (that is, everything is filtered anyway) and it would be fine in our prototype history service if there was a way to do communicate selection. Mdibs in embedded devices may be smaller making handling filtering easier, though that's also the use-case that could benefit from the most from reduced traffic. Maybe handle filtering is only useful for embedded devices? Assuming consumer's take advantage of it (and there's no way to tell if it is available; makes me think should requirements are a little pointless for feature support).

Anyway, your right; new features can always be added and things can be changed. That can take a while, though, and this is just one opportunity to do that but I don't feel strongly about it either way.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added proposed solution to schema.

Comment thread asciidoc/volume2/history-service/tf2-ch-a-mdpws-history-service.adoc Outdated
@d-gregorczyk d-gregorczyk marked this pull request as ready for review June 12, 2026 12:53
@PaulMartinsen PaulMartinsen linked an issue Jun 16, 2026 that may be closed by this pull request
@d-gregorczyk d-gregorczyk requested a review from alex-pe1 June 17, 2026 06:27

@PaulMartinsen PaulMartinsen left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've focused on changes to improve clarity and provide a good starting point for trial implementation.

For a time range-filtered subscription, a <<vol1_spec_sdpi_p_actor_somds_provider>> shall respond with notifications that reflect the MDIB of the <<vol1_spec_sdpi_p_actor_somds_provider>> and its changes in the closed time interval of ++[hm:TimeRange/@StartTime, hm:TimeRange/@EndTime]++.
====

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with data that exceed the interval of ++[hm:TimeRange/@StartTime, hm:TimeRange/@EndTime]++.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NOTE: The time interval is a hint. A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with data that exceeds, or is a subset of, the interval of ++[hm:TimeRange/@starttime, hm:TimeRange/@EndTime]++.


NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with data that exceed the interval of ++[hm:VersionRange/@StartVersion, hm:VersionRange/@EndVersion]++.

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with a subset of data from the interval ++[hm:VersionRange/@StartVersion, hm:VersionRange/@EndVersion]++, e.g., if it cannot fully serve the request due to discarded historic information or filter request that point into the future.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For clarity:

… or filter request that point into the future.

… or the filter requests reports from the future.

****
[NORMATIVE]
====
If it is intended for a <<vol1_spec_sdpi_p_actor_somds_provider>> to include <<term_historic_localized_text>>s in hm:ChangeSequenceReport elements, for an <<term_mdib_sequence_of_changes>> that is requested from a <<vol1_spec_sdpi_p_actor_somds_provider>>, the <<vol1_spec_sdpi_p_actor_somds_provider>> shall transmit filtered <<term_historic_localized_text>>s before transmitting the hm:HistoricMdib or hm:HistoricReport elements that reference the <<term_historic_localized_text>>s.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

simplify for clarity:

The <<vol1_spec_sdpi_p_actor_somds_provider>> transmitting <<term_historic_localized_text>> shall transmit filtered <<term_historic_localized_text>>s before transmitting hm:HistoricMdib or hm:HistoricReport elements that reference the <<term_historic_localized_text>>s.

Note:
This ensures the localized text is available to the <<vol1_spec_sdpi_p_actor_somds_consumer>> before it is used by other elements.

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with data that exceed the interval of ++[hm:VersionRange/@StartVersion, hm:VersionRange/@EndVersion]++.

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with a subset of data from the interval ++[hm:VersionRange/@StartVersion, hm:VersionRange/@EndVersion]++, e.g., if it cannot fully serve the request due to discarded historic information or filter request that point into the future.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is worth pointing this out explicitly:

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with a subset of data that is not contiguous. For example, a complete history of waveform streams may not be available.

====

NOTE: A <<vol1_spec_sdpi_p_actor_somds_provider>> may respond with data that exceed the interval of ++[hm:TimeRange/@StartTime, hm:TimeRange/@EndTime]++.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy from R0516 for consistency.

<xsd:annotation>
<xsd:documentation>The time or MDIB version range to select.</xsd:documentation>
</xsd:annotation>
</xsd:element>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<xsd:element name="Reports" type={space delimited list of desired reports from an enumerated type of reports}...

For example: <Reports>EpisodicMetricReport EpisodicAlertReport</Reports>

Documentation: A space separate list of reports the subscriber is interested in; implied value is all reports. This is a hint to the provider that it may drop reports, e.g., WaveformStream, that are not in the list without impacting the subscribers goals to reduce bandwidth, etc.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<xsd:element name="Handles" type={a white space delimited list of type pm:HandleRef}... <documentation>This is a hint of the containment tree entries desired by the subscriber. The provider may drop reports that don't include the desired entries to reduce bandwidth, etc. The implied value is all reports.</documentation>.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is ok, however, this must be an optional feature as providers may not be able to filter on such granularity (there are implementations out there just storing zipped content and will never unpack and re-zip just because a consumer requested so).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Calling it a "Hint" was my idea to make clear that providers are free to ignore the suggestion if it doesn't suit them.

Comment thread asciidoc/volume2/history-service/tf2-ch-a-mdpws-history-service.adoc Outdated
****
[NORMATIVE]
====
A <<vol1_spec_sdpi_p_actor_somds_consumer>> shall only add exactly one hm:HistoryQuery element to a wse:Subscribe/wse:Filter element with @Dialect =

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to require providers to process a filter node that can include, along with the hm:HistoryQuery element, an unbounded and undefined set of other elements. Is that the intention?

How about:

A filter in the Dialect designated urn:oid:1.3.6.1.4.1.19376.1.6.2.10.1.3.1.1 contains exactly, and only, one hm:QueryFilter of type hm:QueryFilterType.

It seems better to give a concrete specification, and amend it in later versions, if necessary to me. Otherwise, to ensure interoperability, I think we should alert manufacturers that the content can change at any time. Perhaps with a note:

NOTE: The filter may include additional elements and attributes from any namespace, viz:

<xs:complexType name="FilterType" mixed="true"> 
  <xs:sequence> 
    <xs:any namespace="##other" processContents="lax" 
                 minOccurs="0" maxOccurs="unbounded" /> 
    </xs:sequence> 
    <xs:attribute name="Dialect" type="xs:anyURI" use="optional" /> 
    <xs:anyAttribute namespace="##other" processContents="lax" /> 
</xs:complexType>


Once the final report has been sent, the <<vol1_spec_sdpi_p_actor_somds_provider>> sends an empty report and ends the subscription to signify the end of the <<term_history_service>> request.

The <<term_history_service>> allows for limited filtering:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added proposed solution to schema.

Comment thread asciidoc/volume2/dev-32/tf2-dev-32.adoc Outdated
Comment thread asciidoc/volume2/dev-32/tf2-dev-32.adoc Outdated
d-gregorczyk and others added 2 commits June 19, 2026 15:01
Co-authored-by: Alexander Pentzel <89145096+alex-pe1@users.noreply.github.com>
Co-authored-by: Alexander Pentzel <89145096+alex-pe1@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

Add SDPi-P History Service Option to TF-1 History: add LastReport attribute to simplify processing Add SDPi-P History Service Option

5 participants